home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / library / help / tcl / variables / trace < prev    next >
Encoding:
Text File  |  1993-10-26  |  7.3 KB  |  136 lines  |  [TEXT/$Tcl]
  1.  
  2.           trace option ?arg arg ...?
  3.  
  4.  
  5.      DESCRIPTION
  6.           This command causes Tcl commands  to  be  executed  whenever
  7.           certain  operations  are invoked.  At present, only variable
  8.           tracing is implemented. The legal  option's  (which  may  be
  9.           abbreviated) are:
  10.  
  11.           trace variable name ops command
  12.                Arrange for command to be  executed  whenever  variable
  13.                name is accessed in one of the ways given by ops.  Name
  14.                may refer to a normal variable, an element of an array,
  15.                or  to  an  array as a whole (i.e. name may be just the
  16.                name of an array, with  no  parenthesized  index).   If
  17.                name  refers  to a whole array, then command is invoked
  18.                whenever any element of the array is manipulated.
  19.  
  20.                Ops indicates which operations  are  of  interest,  and
  21.                consists of one or more of the following letters:
  22.  
  23.                     r    Invoke command whenever the variable is read.
  24.  
  25.                     w    Invoke command whenever the variable is writ-
  26.                          ten.
  27.  
  28.                     u    Invoke  command  whenever  the  variable   is
  29.                          unset.   Variables  can  be  unset explicitly
  30.                          with the unset command,  or  implicitly  when
  31.                          procedures  return  (all of their local vari-
  32.                          ables are unset).  Variables are  also  unset
  33.                          when  interpreters  are  deleted,  but traces
  34.                          will not  be  invoked  because  there  is  no
  35.                          interpreter in which to execute them.
  36.  
  37.                When the trace triggers, three arguments  are  appended
  38.                to command so that the actual command is as follows:
  39.  
  40.                     command name1 name2 op
  41.  
  42.                Name1 and name2 give the name(s) for the variable being
  43.                accessed:  if the variable is a scalar then name1 gives
  44.                the variable's name and name2 is an  empty  string;  if
  45.                the  variable  is an array element then name1 gives the
  46.                name of the array and name2 gives the  index  into  the
  47.                array;  if  an  entire  array  is being deleted and the
  48.                trace was registered on the overall array, rather  than
  49.                a  single  element, then name1 gives the array name and
  50.                name2 is an empty string.  Op indicates what  operation
  51.                is being performed on the variable, and is one of r, w,
  52.                or u as defined above.
  53.  
  54.                Command executes in the same context as the  code  that
  55.                invoked  the  traced  operation:   if  the variable was
  56.                accessed as part of a Tcl procedure, then command  will
  57.                have  access to the same local variables as code in the
  58.                procedure.  This context may be different than the con-
  59.                text  in  which  the  trace  was  created.   If command
  60.                invokes a procedure (which it normally does)  then  the
  61.                procedure  will  have  to  use  upvar  or uplevel if it
  62.                wishes to access the traced variable.  Note  also  that
  63.                name1  may not necessarily be the same as the name used
  64.                to set the trace  on  the  variable;   differences  can
  65.                occur  if the access is made through a variable defined
  66.                with the upvar command.
  67.                For read and write traces, command can modify the vari-
  68.                able  to affect the result of the traced operation.  If
  69.                command modifies the value of a variable during a  read
  70.                or  write trace, then the new value will be returned as
  71.                the result of the traced operation.  The  return  value
  72.                from   command  is ignored except that if it returns an
  73.                error of  any  sort  then  the  traced  operation  also
  74.                returns  an  error with the same error message returned
  75.                by the trace command (this mechanism  can  be  used  to
  76.                implement read-only variables, for example).  For write
  77.                traces, command is invoked after the  variable's  value
  78.                has  been  changed;  it  can write a new value into the
  79.                variable to override the original  value  specified  in
  80.                the write operation.  To implement read-only variables,
  81.                command will have to restore the old value of the vari-
  82.                able.
  83.  
  84.                While command is  executing  during  a  read  or  write
  85.                trace, traces on the variable are temporarily disabled.
  86.                This means that reads and  writes  invoked  by  command
  87.                will  occur  directly, without invoking command (or any
  88.                other traces) again.  However, if  command  unsets  the
  89.                variable then unset traces will be invoked.
  90.  
  91.                When an  unset  trace  is  invoked,  the  variable  has
  92.                already  been  deleted:  it will appear to be undefined
  93.                with no traces.  If an unset occurs because of  a  pro-
  94.                cedure  return,  then  the trace will be invoked in the
  95.                variable context of the procedure  being  returned  to:
  96.                the  stack  frame  of  the  returning procedure will no
  97.                longer exist.  Traces are  not  disabled  during  unset
  98.                traces,  so  if  an  unset  trace command creates a new
  99.                trace and accesses the  variable,  the  trace  will  be
  100.                invoked.  Any errors in unset traces are ignored.
  101.  
  102.                If there are multiple traces on  a  variable  they  are
  103.                invoked  in  order  of creation, most-recent first.  If
  104.                one trace returns an error, then no further traces  are
  105.                invoked  for  the  variable.  If an array element has a
  106.                trace set, and there is also a trace set on  the  array
  107.                as  a  whole, the trace on the overall array is invoked
  108.                before the one on the element.
  109.  
  110.                Once created, the trace remains in effect either  until
  111.                the  trace  is  removed  with the trace vdelete command
  112.                described below, until the variable is unset, or  until
  113.                the  interpreter  is  deleted.  Unsetting an element of
  114.                array will remove any traces on that element, but  will
  115.                not remove traces on the overall array.
  116.  
  117.                This command returns an empty string.
  118.  
  119.           trace vdelete name ops command
  120.                If there is a trace  set  on  variable  name  with  the
  121.                operations  and  command given by ops and command, then
  122.                the trace is removed, so that command will never  again
  123.                be invoked.  Returns an empty string.
  124.  
  125.           trace vinfo name
  126.                Returns a list containing one element  for  each  trace
  127.                currently  set  on  variable name.  Each element of the
  128.                list is itself a list containing  two  elements,  which
  129.                are  the ops and command associated with the trace.  If
  130.                name doesn't exist or doesn't have any traces set, then
  131.                the result of the command will be an empty string.
  132.  
  133.  
  134.      KEYWORDS
  135.           read, variable, write, trace, unset
  136.